Cream of the Crop 3

home *** CD-ROM | disk | FTP | other *** search

/ Cream of the Crop 3 / Cream of the Crop 3.iso / comm / reputil5.zip / READ.ME < prev next >

Wrap

Text File | 1993-11-17 | 26KB | 602 lines

. REPUTIL5--17NOV93 REP PACKET UTILITY PACKAGE V5 Copyright (c) 1993, Frank F. Yates Licensed for Free Public Use . .COPYRIGHT and LICENSE This package is copyright in 1993 by Frank F. Yates, but it is dedicated to public use without charge. It is free to all. The original distribution file "REPUTIL5.ZIP" may be distributed freely, provided that it is not changed in any respect. Any person may use the programs in this file for his own purposes without limitation. No part of this package be distributed except in the complete and original REPUTIL5.ZIP file. .WARRANTY This package and the programs which it contains are absolutely not warranted in any way or for any purpose. So far as I know, it works just fine, but the risk of using it must be yours! Always be sure your files are backed up before trying ANY new software. .FILE LIST This package contains the following files: 1. FILE_ID.DIZ Short Description for the BBS File Directory 2. READ.ME Description of the package 3. WRITEREP.EXE Program to convert the text REPLY file into bbs.MSG 4. READREP.EXE Program to convert bbs.MSG into formatted text messages 5. REPLY Sample Reply file as input 6. MYBBS.MSG Result of executing WRITEREP on REPLY 7. MYBBS.REP Result of compressing MYBBS.MSG with PKZIP 8. ECHO Text extracted back out of MYBBS.MSG by READREP File 1 is only for your BBS, and for any subsequent BBS to which this package might be uploaded. File 2 is the Reference Manual for the REPUTIL package. You should read it carefully and try out for yourself the features explained in it. Then put this away for possible future reference. Files 3 and 4 are the executable part of the package. These two programs should be copied to any library of your choice which is in your command path. Files 5 is a sample starting file containing three messages which were created with a text editor. Files 6, 7, and 8 were the result of execution of the REPGEN.BAT procedure described below in the AUTOMATIC EXECUTION Section. The BBS environment variable was set to MYBBS for the demonstration. (eg. C:>SET BBS=MYBBS). In actual practice, you want to set BBS to the name of the BBS to which you are going to send your messages. .FILE_ID.DIZ REPUTIL V5 17 OCT 93 FREEWARE. (No charge) A pair of utility programs to write and read the ".REP" packets which are used to send a block of messages to a BBS (Bulletin Board System). All you need is a text editor and REPUTIL to create your own REP packets and upload batches of messages. These are simple programs with a lot of flexibility. Messages can also be read from QWK packets. NOTE: The above is an exact copy of the FILE_ID.DIZ file included in in this REPUTIL V5 package (REPUTIL5.ZIP). The file name is noted by the BBS upon upload, and the brief description which the file contains is automatically entered into their File Directory. This system makes it unnecessary to enter on-line a lengthy description of the package to be uploaded. It also standardizes the description so that the author's original words are preserved as the package is passed by users from BBS to BBS by downloading and uploading. .VERSION HISTORY Version 3 (27 Sept 91) ------------------------ * The first public release of REPUTIL Version 4 (30 Sept 91) ------------------------ * The Documentation was revised READREP.EXE Progrm ------------------ * allow message lines of any length WRITEREP.EXE Program -------------------- * Translate all null lines into a single space * Permit the use of "=" as alternative to ":" in Keyword syntax * Permit a leading "#" on the number of a referenced message * Improve the display of message headers during execution Version 5 (17 Nov 93) ----------------------- * The Documentation was revised READREP.EXE Program ------------------- * The output message header has been re-designed to be more similar to current PCBoard messages, and to accommodate the maximum field lengths (Subj:, From:, and To:) permitted by the QWK format ie. 25 bytes each. WRITEREP.EXE Program -------------------- * The binary field at +123 bytes defining the Conference number was lengthened from 1 byte (255 limit) to 2 bytes (32,767 limit). Apparently this field has always been 2 bytes long. I just did not know it. * The default max line length is increased to 150 bytes. WRITEREP truncates lines greater than a limit controlled by the "LLX" parameter. This can be controlled by you, but previously the default was 80 bytes, which too-often truncates lines when you do not expect it to. * A "0" is now written into the "Ref" field of the QWK header record if no message is referenced. This change is required by PCBoard Version 15.0. .What are all the little "." marks on the document sections? These little dots (just ordinary periods) are "Module Identifiers", which permit "FRANK's READER" to create an index of a document and to access the sections individually from the index. Frank's Reader is ideal for studying text files (such as this one) without having to print them, but it is not required in order to use REPUTIL. Frank's Reader is very handy for reading the messages in any format and for the general management of text files. It is shareware. Version 16, released in 1991 may still be available on COMPUSERVE, and a few other places, including RESEARCHER's BBS, or contact the author via Internet: frank.yates@spacebbs.com . .INTRODUCTION Bulletin Board Systems (BBS) in the beginning were designed for on-line interactive use, where the user would read messages while connected to the board, and compose replies and new messages in real time. This can still be done, but is no longer the common practice. The thousands of messages which are available on most BBS make live interaction too time consuming and too costly (in phone bills). Also, the quality of work which can be done in real-time is often not the best. The common practice today is for users of BBS systems is to work off-line, where they: 1. Call the BBS and download a packet of messages, either thru a Mail Door, or directly from the board. Then immediately hang up. 2. Read these messages at leisure, using an Off-Line Mail Reader, (such as "SLMR", the Silly Little Mail Reader, which is free now). Good replies and new messages are composed using such a reader or other software, creating a "REP" packet containing them. 3. Call the BBS again, and upload the REP packet, from which the BBS extracts the replies and new messages and enters them into its message database. .QWK/REP FORMAT The format of the QWK/REP packets is used by many Bulletin Board Systems and has become essentially an industry standard. It is best described in a file: QWKLAY16.ZIP by Patrick Y. Lee, which is available for download on many BBS. An excerpt from that file, provides background on the QWK/REP system. ------------------- Excerpt from QWKLAY16.ZIP ---------------------- [1.2] History The QWK-format was invented by Mark "Sparky" Herring in 1987. It was based on Clark Development Corporation's PCBoard version 12.0 message base format. Off-line mail reading has become popular only in recent years. Prior to summer of 1990, there were only two QWK-format off- line mail reader programs. They were Qmail DeLuxe by Mark Herring and EZ-Reader by Eric Cockrell. Similarly for the doors, there were only two -- Qmail by Mark Herring and MarkMail by Mark Turner. They were both for PCBoard systems. A lot has changed in both off-line reader and mail door markets since summer 1990. Now, there are more than a dozen off-line mail readers for the PC. Readers for the Macintosh, Amiga, and Atari exist as well. There are over a half dozen doors for PCBoard, and QWK-format doors exist for virtually all of the popular BBS softwares. All of these happened in less than two years! More readers and doors are in development as I write this, keep up the excellent work. In addition to doors, some BBS softwares has QWK-format mail facility built in. Off-line mail reading is an integral part of BBS calling. Conference traffic and selection on all networks have grown dramatically in re- cent years that on-line reading is a thing of the past. Off-line mail reading offers an alternative to reading mail on-line -- It offers speed that cannot be achieved with on-line mail reading. The reason why QWK-format readers and doors seem to have gained popu- larity is probably dued to its openness. The format is readily avail- able to any programmer who wishes to write a program that utilize it. Proprietary is a thing of the past, it does not work! Openness is here to stay and QWK-format is a part of it. QWKLAY16.ZIP is Copyright 1992 by Patrick Y. Lee. The QWK-format is Copyright 1987 by Sparkware. ----------------- End-of-Excerpt from QWKLAY16.ZIP ----------------- .OFF-LINE MAIL READERS Many "Mail Readers" are available, some of which are very good. Most read ".QWK" packets and create ".REP" packets. The readers provide a convenient platform for viewing and generating messages. I use one myself, and it is not my purpose to denigrate Mail Readers. They do have certain limitations however, which are overcome by the REPUTIL utilities. I consider REPUTIL to be an adjunct to a mail reader rather than a replacement. REPUTIL itself cannot be called a Mail Reader because it does not include many of the automatic features common in Mail Readers. REPUTIL can be used without a Mail Reader though, and it can do some things which most Mail Readers can't, such as reply to messages which are not available locally in QWK packets. It can also read messages of any length, which some Mail Readers can't. .REPUTIL Its Purpose, Function, and Use The REPUTIL package contains two programs (WRITEREP, and READREP) which will run on IBM PC type computers under the DOS operating system and others which are DOS compatible. It also contains this DOC file, which may have some merit by itself as information for BBS users. BBS messages must necessarily spring from a text editor. Often this editor is called from a mail reader, and may even be built into the mail reader. You can use any old text editor however to generate a message, or even a word processor in text mode, and you do not need a Mail Reader to do it. Once having produced one or more messages in a text file, it is easy using WRITEREP to create a REP packet which can carry these messages up to a BBS. The instructions on how to do this follow. . .HOW TO CREATE A REPLY FILE The first step in uploading a batch of messages is to write the messages by any means available, and accumulate them in a text file, which for convenience we will call "REPLY". As you write each message, include a "Header" line before the message text containing the routing information needed by the BBS. The syntax of the Header is: # To:xxx Sub:xxx The "#" must be in column 1, and identifies this line as a message header. The two keyword parameters which follow are required for all messages. To: is the addressee of the message, Sub: is the subject. Either of these can contain up to 25 characters, including embedded blanks. "Subj" will work instead of "Sub" if you prefer. If the subject entered is too long, it will be truncated by WRITEREP at 25 characters. If you want to send a message to a Conference other than "0", then you may add Conf:n or Cnf:n to the header, where "n" is the Conference number. The number must be used rather than the name because that is the requirement for the REP packet, and WRITEREP is not set up to process conference names. The Conference numbers are available from the Conference list generated by the (J)oin command (for PCBoard BBS). They also appear in the CONTROL.DAT file of a QWK packet, if you happen to have one of those. If your message replies to or references another message, you may cite the number of that message: Ref:n This permits your message to be easily found by others as part of the thread. If you wish your message to be private rather than public, you may add the word "PVT" as the first word in the line after "#". An example of a message using all these options follows: ============================================================================ #PVT To:Somebody Sub:Syntax Example #1 Conf:50 Hello, This is a message illustrating the syntax of the control header for batch messages to be processed by WRITEREP into an un-compressed .REP packet. Other examples can be found in the sample REPLY file which comes with the REPUTIL package. Regards, Frank ============================================================================ You may use small letters or capitals for the keyword parameters, and the value "xxx" may be separated from the ":" by a space if you prefer. The beginning of each keyword must be separated from the end of the preceding data field by one or more spaces. The parameters may be written in any order, except that if "PVT" is used, it must be first. .HEADER LINE SYNTAX * A "#" in column 1 is required for all headers, and this character must not appear in column 1 of any line of text in your messages. This is the way WRITEREP identifies the end of the previous message and the beginning of a new one. * All control parameters must appear on a single line, which can be longer than 80 bytes if necessary. * The parameters can be in any order, except "PVT", which must be first if it is used. * The parameters are separated from each other by one or more spaces. Commas are not used. * Additional spaces may be used in the header line for readability. They will be ignored, except within the To, From, and Subject fields, where they are retained as entered. * Parameter names and values may be in small letters or capitals, or mixtures of these. * Four of the parameters (CNF, LCX, LLX, REF) require numeric values. Supplying a a non-numeric value for one of these will cause WRITEREP to abend. * In the keyword parameters, "=" may be used in place of ":" as a separator, whichever you prefer. This is true for either the command line parms or the message headers. * The value assigned to the parameter may begin immediately following the separator (: or =), or it may be separated by one or more blanks. .COMMAND LINE SYNTAX The command line syntax for WRITEREP is: -------- Optional ---------- C:> WRITEREP infile outfile {Fr:your name} {LCX:n} {LLX:n} If you do not supply infile and/or outfile, the program will ask you for these names. The other parameters are optional, but including your name is recommended, because otherwise you will have to include it in the first message header, which you might forget to do. The infile name can be anything, but the outfile name is critical. It must be of the form "bbs.MSG", where "bbs" is the identifier used by your BBS for Mail Door Packets. If you don't know what this is, ask your SYSOP. It is necessary to scratch any existing output file before executing WRITEREP because otherwise an unusable file could result from a combination of new messages with the old ones. The command line syntax for READREP is: C:> READREP infile outfile Again if the input and output files are not supplied as command line parameters the program will prompt you for them. .PARAMETER LIST The following parameters may be used in message header lines. "To" and "Sub" are required for every message, as is "Fr" unless you have included that in the command line. The other parameters are optional. PARM DESCRIPTION -------- ----------------------------------------------------------- PVT Private Message Flag. If used, must be the first parameter Cnf:n Conference Number (defaults to 0) Conf:n Fr:xxx Your Name as sender of the message (25 chars max) From:xxx LCX:n Max number of lines per message. Messages will be split into parts if this number is exceeded (default 95) LLX:n Maximum length of a message line. (default 150) Ref:n Number of Referenced Message (optional) Sub:xxx Subject of the message (25 chars max) Subj:xxx To:xxx Addressee of Message (25 chars max) The following parameters may be used on the command line. --------------------------------------------------------- Fr:xxx From:xxx LCX:n LLX:n .HOW TO CREATE a REP PACKET and POST YOUR MESSAGES Once you have a REPLY file containing one or more messages, the following steps will send your message(s) to the BBS. A BAT procedure can automate them for you, as described in the next section. 1. Execute WRITEREP to create a file called "bbs.MSG". --------------------------------------------------- C:>WRITEREP reply bbs.MSG (NOTE: replace "bbs" with your BBS name) 2. Compress bbs.MSG into bbs.REP ----------------------------- C:>PKZIP bbs.REP bbs.MSG (NOTE: the operand order is reversed) "bbs" is a word, not more than 8 bytes long, which is used to define your BBS in QWK and REP packets. You can ask your SYSOP, or download a QWK packet and see what it is called. NOTE: It is important to enter CAPITAL LETTERS on this command, because if you enter small letters the REP file may have small letters in its name (under some operating systems), and then you may find that the BBS will reject the file for upload. The BBS wants CAPITAL letters in its REP packet names. For example, the RESEARCHER's BBS creates QWK packets called "RESEARCH.QWK". To upload replies to this BBS, you send up a file called "RESEARCH.REP". 3. Call the BBS, and upload the bbs.REP packet ------------------------------------------- This can be direct to a PCBoard V15.0 BBS via a "QWK U" command, or thru a variety of Mail Doors on various types of BBS. .AUTOMATIC EXECUTION It is convenient to automate the conversion of the REPLY file into a REP packet. Following is a procedure which does this. It requires that you first identify the BBS in your DOS environment table. Do this by the command:> SET BBS=bbs (for "bbs", enter the correct identifier). You could of course replace %BBS% in this procedure by %1, and supply the BBS name as an operand, if that would be more convenient. NOTE: Use CAPITAL LETTERS in your "SET BBS=" command. See note in the the previous section. @ECHO OFF REM REPGEN.BAT--10NOV93 Translate the REPLY file into a REP packet REM REM ---Convert messages in REPLY to a REP Packet for PCBoard IF "%BBS%"=="" GOTO NOBBS IF EXIST %BBS%.MSG DEL %BBS%.MSG WRITEREP REPLY %BBS%.MSG Fr:Frank Yates ****INSERT YOUR NAME HERE**** REM REM ---Zip it up for transmission IF ERRORLEVEL 1 GOTO FIN IF EXIST %BBS%.REP DEL %BBS%.REP PKZIP -a %BBS%.REP %BBS%.MSG REM REM ---Convert back to ASCII to check **** This step is optional **** IF ERRORLEVEL 1 GOTO FIN READREP %BBS%.MSG ECHO IF ERRORLEVEL 1 GOTO FIN IF EXIST ECHO FR ECHO <<< This calls Frank's Reader to look at ECHO GOTO FIN :NOBBS ECHO *** SET BBS :FIN NOTES: 1. Your name can be supplied as a command line parameter to WRITEREP, as illustrated in the above procedure, or it can be supplied in the first message header. Putting it in the procedure is easier, and is recommended. If you do both, the name used in any message header becomes the new default for subsequent messages in the packet. The name you supply must match exactly the name which you use to sign on to the BBS. This name is inserted into the REP packet, and your messages will be refused if the name is not right. The syntax is "Fr:first last". Either small letters or capitals will work. 2. You may specify two additional parameters on the WRITEREP execution line if you wish: LCX=n The maximum number of lines in a message out of WRITEREP. The default is 95. Messages containing more than 100 lines occur frequently (unfortunately), and messages containing many hundreds of lines are seen now and then. It is good practice however to limit any single message to not more than 95 lines to be sure that everyone who sees your message will see it all. With WRITEREP, you can create a message as long as you like, and WRITEREP will split it into smaller messages not exceeding the value of LCX. LLX=n The maximum length of any line in a message. The default is 140. Input lines longer than this will be truncated. Ordinarily new message lines should be limited to 71 columns so that they are not folded on some computers, and to leave room for quoting prefixes added by those who reply to and quote your messages. The purpose of LLX is to allow you to insure that message lines do not exceed some desired limit for a particular application. .HOW TO INSPECT A REP PACKET You may want to double-check your first few REP packets to be sure that you have done it all right. C:>PKUNZIP bbs.REP (recovers "bbs.MSG") C:>READREP bbs.MSG ECHO (creates ECHO file, which is text) .HOW TO INSPECT A QWK PACKET READREP was not intended to read QWK packets. This was a surprise extra benefit resulting from the similarity in format between REP and QWK. The messages in a QWK packet are contained in the file "MESSAGES.DAT", but they have almost the same format as the "bbs.MSG" file in a REP packet. The main difference is that the Conference number field in QWK packets is used to contain the message number. To figure out the conference number of a message, you need to access the xxxx.NDX files and search for a pointer to that message. READREP does not do this. Ordinarily there is no reason to use READREP for QWK packets, since if your intent is to process messages as text files, you are better off downloading compressed text files in the first place instead of QWK packets. For one thing, that way your subject and address fields will not be truncated to 25 bytes. There is one case however in which READREP is handy with respect to QWK packets. If you are reading messages with your Mail Reader and come across in interesting one which has been truncated at 100 lines or 150 lines, etc. you can note the number of the message and later use READREP to extract it from the QWK packet. I used to do this a lot with Internet and UseNet messages before I stopped using the Mail Reader for them altogether. STEP 1. C:>PKUNZIP bbs.QWK (recovers "MESSAGES.DAT") This step may not be necessary if you can shell out of your Mail Reader and look at its work directory, or exit from it and leave the work directory intact. 2. C:>READREP MESSAGES.DAT NEW.MSG (creates NEW.MSG file) .NAMES and ADDRESSES CLARK DEVELOPMENT Co, Inc. Source of the PCBoard BBS software 6000 S. Fashion Blvd. Suite 101 Murray, UT 84107 U.S.A. Voice: (801) 261-1686 Fax: (801) 261-8987 BBS: (801) 261-8974 PKWARE Inc. Source of the "PKZIP" Compression Utilities 9025 North Deerwood Drive Brown Deer WI 53223 BBS: (414) 354-8670 RESEARCHER's BBS Our local BBS. They have many many files. P.O Box 1715 The SYSOPs are friendly. Lancaster, CA 93539 You can register as a guest and download BBS: (805) 949-8151 some software and leave messages. Frank F. Yates Who put REPUTIL together for your benefit. 21340 N. Charlene Place To reach me, leave a message on Researcher's, California City, CA 93505 or send to Internet: frank.yates@spacebbs.com